Split `Bundle` and `StaticBundle` #19761

SkiFire13 · 2025-06-21T08:54:30Z

Objective

Splitted off from Bundle refactor - Option bundles and Box<dyn Bundle> #19491
Split Bundle into one type representing a static set of component types (StaticBundle) and one that will be used for representing a possibly dynamic set of components.

Solution

Create a new StaticBundle type, mirroring Bundle for now
Switch all APIs that need to statically know the components in a Bundle (i.e. from its type) to use StaticBundle
Add &self parameters to Bundle to ensure all APIs that use it have a concrete instance to work with in the future.

Additional notes

For now this doesn't do anything functionally, as Bundle still requires the components to be statically fixed. However this opens the doors for changes to the Bundle trait that allow dynamic components without impacting APIs that actually rely on static components.

ElliottjPierce

Looks good to me. The parallel contents of code for StaticBundle vs Bundle is kinda annoying, but I know that's changing in the next prs, so I'm not worried about it.

crates/bevy_ecs/src/bundle.rs

release-content/migration-guides/static-bundle-split.md

crates/bevy_ecs/src/bundle.rs

alice-i-cecile

Some small notes on docs that I think we should clean up quick. I would really appreciate a paragraph or two of module docs laying out these traits and how they interconnect, but that's fine to leave to follow-up if you prefer.

More importantly, I'm not sure why we should keep a split between DynamicBundle and Bundle around after these changes. It looks like Bundle should now be object-safe, allowing us to merge them together.

I haven't done a deep dive on this area of the code in a while though, so please feel free to explain why we can't / shouldn't do that :)

SkiFire13 · 2025-06-23T05:29:53Z

More importantly, I'm not sure why we should keep a split between DynamicBundle and Bundle around after these changes. It looks like Bundle should now be object-safe, allowing us to merge them together.

Bundle is not object safe yet (it still has a bunch of generic functions without where Self: Sized) but this will change in a followup PR.

However even then it will be a bit of a hassle to remove DynamicBundle. In the unsplitted PR I limited myself to renaming it to ComponentsFromBundle to avoid confusion with dynamic bundles after trying to remove it. The issue is that the insert_by_ids method internally uses it with a struct wrapping some OwningPtrs, which is not Send + Sync + 'static, while Bundle requires them (but not DynamicBundle/ComponentsFromList!). Removing those requirements is possible but leads to ton of boilerplate elsewhere (e.g. all commands require them).

JaySpruce

LGTM. Bundles always felt kind of 'messy' to me, and this direction feels tidier.

SkiFire13 added 18 commits June 21, 2025 10:45

Introduce StaticBundle

c53f10a

Implement StaticBundle for Components

a015f7d

Implement StaticBundle for tuples of StaticBundles

fd52029

Implement StaticBundle in the derive macro

9bb3f3c

Implement StaticBundle for SpawnRelatedBundle and SpawnOneRelated

ebc4143

Split Bundles methods for Bundle and StaticBundle

e806f5e

Switch Entity{Ref,Mut}Except to StaticBundle

07f6d1d

Switch Observer and Trigger to StaticBundle

ddd69c5

Require StaticBundle in ReflectBundle

9b0ab87

Switch EntityClonerBuilder to StaticBundle

9a176a5

Require StaticBundle in batch spawning

bd30a8b

Switch component removal to StaticBundle

28a21bd

Switch EntityWorldMut::retain to StaticBundle

c33033a

Require StaticBundle in ExtractComponent

a44cf37

Add support for #[bundle(dynamic)] attribute

e683a10

Add migration guide

4a0f69e

Add &self parameter to Bundle methods

ef88ad8

Fix warning

5942b7a

ElliottjPierce approved these changes Jun 21, 2025

View reviewed changes

ElliottjPierce added A-ECS Entities, components, systems, and events S-Needs-Review Needs reviewer attention (from anyone!) to move forward labels Jun 21, 2025

alice-i-cecile added C-Code-Quality A section of code that is hard to understand or change X-Contentious There are nontrivial implications that should be thought through labels Jun 22, 2025